feat(settings): give this PC a public address through Portal - #746

Change

This is step 2 of #202, as a draft to discuss. Settings → Phone & devices → Portal gives this PC a public HTTPS address through Portal. It runs the command the guide already documents, using the portal already on the PC. The app never installs Portal, Tailscale stays the default route, and tailscale.ts stays read-only.

What the group shows:

• No portal, or one older than v2.6.1: a single line that says so, with a link to Portal's install.
• Ready: a Relay field and Start.
  • Start first asks the relay's /sdk/domain whether it runs v2.6.1 or later.
  • It then runs portal expose --http-route /=<port> --strip-request-header Tailscale-User-Login --name herdr-<random> --identity-path <state dir>/portal/identity.json --relays <relay> --discovery=false --hide.
• Running: the address from Portal's service ready at line, with its QR code (through PhonePanel's Address), and a Relay row with Stop.
• Blocked: one line that names the setting to change and says to restart the app.

Rules the server enforces, whatever the request says:

• Start is refused without HERDR_WEB_TOKEN (409 token_required) and while HERDR_WEB_TAILSCALE_SERVE_ONLY=1 (409 serve_only). This follows the guide from docs(guide): a public HTTPS address with Portal #229, which says to set a token before starting Portal.
• Any device that can type can start and stop it. A watch-only device gets read_only. Both POSTs need same-origin and x-herdr-update: 1, like the update POSTs.
• Only the relay comes from the request, as one https origin. A comma is refused because --relays takes a list.
• Portal's environment is PATH, home, temp and proxy variables only, so the token never reaches it.

Lifecycle:

• At start, the server first stops a Portal that an earlier server left running (one killed outright, say). It identifies that Portal by the pid in state.json and checks with ps, or the Windows process table, that the process is portal expose on this identity. This happens before the token check, so a server restarted without a token keeps no public address.
• An address that was on then comes back, since an app update restarts the server. A server on another port that shares the state directory leaves the other server's Portal alone.
• On shutdown the entrypoint waits for Portal to exit before it exits itself. Portal gets SIGTERM so it can unregister, then SIGKILL after 4 s, within the 6 s the supervisor allows.
• Portal retries a relay it cannot use forever, so readiness has a 60 s deadline of its own. A relay operation failed permanently line stops it too. Errors quote Portal's last warning or error line.

Docs:

• the guide's Portal section;
• the "Do I need Tailscale?" FAQ and the privacy FAQ, since the relay sees connection metadata and holds the address's certificate;
• the uninstall note and the HERDR_WEB_STATE_DIR row;
• DESIGN.md (page list and the group), a server/AGENTS.md row, ko/ja/zh strings, a demo answer (supported: false) and a changelog line.

The README and site still say the app "brings no tunnel". That stays true, since Portal is installed separately, so I left them alone.

Questions for you:

• Start/Stop, or the read-only copyable command gosunuts asked about on feat: support Portal Tunnel as a remote-access backend #202? I can cut this down to the latter.
• Token only, or "paired or token" as in your step-2 description?
• I have not run any of this on Windows.

Refs #202.

Validation

• bun run check fast (macOS arm64, with TMPDIR/CHECK_DIR under /tmp, because macOS's default temp path makes socket paths longer than 100 bytes): generated types, typecheck, build and test:unit all pass (2386 tests, 0 failures).
• server/portal.test.ts (17 tests) uses a stand-in portal script and an injected fetch. It covers:
  • relay and ready-line parsing, including a comma in the relay;
  • no start without a token or under serve-only;
  • the exact flags, and that neither HERDR_WEB_TOKEN nor Portal's IDENTITY_PATH reaches the child;
  • stop remembered across a restart;
  • shutdown waiting for Portal, then resume;
  • taking over from a Portal left by a killed server;
  • a restart without a token stops that leftover Portal and starts nothing;
  • a server on another port leaving it alone;
  • a relay or portal older than v2.6.1 refused before anything runs;
  • the readiness deadline, the permanent-failure line, a crash reported with Portal's last error line, and SIGKILL after the grace period;
  • the endpoint's header, origin, relay, token and method checks.
• Contract tests, through bun run check run … -t "Portal API|watch": 2 pass.
  • New Portal API test in server/api.contract.test.ts: 401 without the token; status; start reaches running with the address; stop.
  • The watch-device test in server/device-access.contract.test.ts now also expects 403 on portal/start and portal/stop.
• Live UI on a herdr-web-ui-test session (token set), with no relay contacted:
  • with Portal v2.6.1 on PATH, the Relay field and Start, at desktop width and phone width (the row stacks);
  • with v2.5.0 on PATH, "This PC has Portal v2.5.0; the app needs v2.6.1 or later. Get Portal".
  • Screenshots are attached below. The running state (address and QR code) is covered by the tests with a stand-in, not by a live relay.